---
title: Browser
sidebarTitle: Browser
description: Configure Stagehand on Browserbase or locally
---
import { V3Banner } from '/snippets/v3-banner.mdx';

<V3Banner />


Stagehand supports two primary environments:

- **Browserbase** - Cloud-managed browser infrastructure optimized for production web automation at scale
- **Local** - Run browsers directly on your machine for development and debugging

## Browserbase Environment

Browserbase provides managed cloud browser infrastructure optimized for web automation at scale. It offers advanced features like stealth mode, proxy support, and persistent contexts.

<Card icon="cloud" title="Browserbase" href="https://docs.browserbase.com" description="Explore the features and benefits of using Browserbase for scalable web automation.">
  Discover the power of cloud-managed browser infrastructure with Browserbase.
</Card>

### Environment Variables

Before getting started, set up the required environment variables:

<CodeGroup>
```bash .env
BROWSERBASE_API_KEY=your_api_key_here
BROWSERBASE_PROJECT_ID=your_project_id_here
```
</CodeGroup>

<Tip>
Get your API key and Project ID from the [Browserbase Dashboard](https://browserbase.com/overview)
</Tip>

### Using Stagehand with Browserbase

#### Basic Setup

The simplest way to get started is with default settings:

```typescript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
});

await stagehand.init();
```

#### Advanced Configuration

Configure browser settings, proxy support, and other session parameters:
```typescript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  // Optional: API Key and Project ID will be pulled directly from your environment
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  browserbaseSessionCreateParams: {
    proxies: true,
    region: "us-west-2",
    browserSettings: {
      viewport: { width: 1920, height: 1080 },
      blockAds: true,
    },
  },
});

await stagehand.init();
console.log("Session ID:", stagehand.sessionId);
```

<Accordion title="Advanced Browserbase Configuration Example">
    ```typescript
const stagehand = new Stagehand({
      env: "BROWSERBASE",
      apiKey: process.env.BROWSERBASE_API_KEY,
      projectId: process.env.BROWSERBASE_PROJECT_ID,
      browserbaseSessionCreateParams: {
        projectId: process.env.BROWSERBASE_PROJECT_ID!,
        proxies: true,
        region: "us-west-2",
        timeout: 3600, // 1 hour session timeout
        keepAlive: true, // Available on Startup plan
        browserSettings: {
          advancedStealth: false, // this is a Scale Plan feature - reach out to support@browserbase.com to enable
          blockAds: true,
          solveCaptchas: true,
          recordSession: false,
          viewport: {
            width: 1920,
            height: 1080,
          },
        },
        userMetadata: {
          userId: "automation-user-123",
          environment: "production",
        },
      },
    });
    ```
</Accordion>

### Alternative: Browserbase SDK

If you prefer to manage sessions directly, you can use the Browserbase SDK:

```typescript
import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ 
  apiKey: process.env.BROWSERBASE_API_KEY! 
});

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  // Add configuration options here
});
```

#### Connecting to an Existing Session

Connect to a previously created Browserbase session using its session ID:

```typescript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionID: "existing-session-uuid-here",
});

await stagehand.init();
console.log("Resumed Session ID:", stagehand.sessionId);
```

## Local Environment

The local environment runs browsers directly on your machine, providing full control over browser instances and configurations. Ideal for development, debugging, and scenarios requiring custom browser setups.

### Environment Comparison

| Feature | Browserbase | Local |
| --- | --- | --- |
| **Scalability** | High (cloud-managed) | Limited (local resources) |
| **Stealth Features** | Advanced fingerprinting | Basic stealth |
| **Proxy Support** | Built-in residential proxies | Manual configuration |
| **Session Persistence** | Cloud context storage | File-based user data |
| **Geographic Distribution** | Multi-region deployment | Single machine |
| **Debugging** | Session recordings & logs | Direct DevTools access |
| **Setup Complexity** | Environment variables only | Browser installation required |
| **Cost** | Usage-based pricing | Infrastructure & maintenance |
| **Best For** | Production, scale, compliance | Development, debugging |

### Basic Local Setup

```typescript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL"
});
  
await stagehand.init();
console.log("Session ID:", stagehand.sessionId);
```

### Advanced Local Configuration

Customize browser launch options for local development:

```typescript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    headless: false, // Show browser window
    devtools: true, // Open developer tools
    viewport: { width: 1280, height: 720 },
    executablePath: '/opt/google/chrome/chrome', // Custom Chrome path
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-web-security',
      '--allow-running-insecure-content',
    ],
    userDataDir: './chrome-user-data', // Persist browser data
    preserveUserDataDir: true, // Keep data after closing
    chromiumSandbox: false, // Disable sandbox (adds --no-sandbox)
    ignoreHTTPSErrors: true, // Ignore certificate errors
    locale: 'en-US', // Set browser language
    deviceScaleFactor: 1.0, // Display scaling
    proxy: {
      server: 'http://proxy.example.com:8080',
      username: 'user',
      password: 'pass'
    },
    downloadsPath: './downloads', // Download directory
    acceptDownloads: true, // Allow downloads
    connectTimeoutMs: 30000, // Connection timeout
  },
});

await stagehand.init();
```

## Advanced Configuration

### DOM Settle Timeout

Configure how long Stagehand waits for the DOM to stabilize before taking actions.

```typescript
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 3000 // Wait up to 3 seconds for DOM to settle
});
```

#### What is DOM Settling?

DOM settling ensures that:
- **Animations complete** before interacting with elements
- **Lazy-loaded content** has time to appear
- **JavaScript updates** finish before actions are taken
- **Dynamic content** is fully rendered

#### When to Adjust

Increase `domSettleTimeout` for pages with:
- Heavy animations or transitions
- Lazy-loading or infinite scroll
- Dynamic JavaScript frameworks (React, Vue, Angular)
- Complex single-page applications

```typescript
// For fast, static pages
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 500 // Minimal wait
});

// For dynamic, animated pages
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 5000 // Longer wait for stability
});
```

<Warning>
Setting `domSettleTimeout` too low may cause actions to fail on elements that aren't ready. Setting it too high increases execution time unnecessarily.
</Warning>

## Troubleshooting

<AccordionGroup>
<Accordion title="Browserbase Authentication Errors">
- Verify your `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` are set correctly
- Check that your API key has the necessary permissions
- Ensure your Browserbase account has sufficient credits
</Accordion>

<Accordion title="Local Browser Launch Failures">
- Install Chrome or Chromium on your system
- Set the correct `executablePath` for your Chrome installation
- Check that required dependencies are installed (Linux: `libnss3-dev libatk-bridge2.0-dev libgtk-3-dev libxss1 libasound2`)
</Accordion>

<Accordion title="Session Timeout Issues">
- Increase session timeout in `browserbaseSessionCreateParams.timeout`
- Use `keepAlive: true` for long-running sessions
- Monitor session usage to avoid unexpected terminations
</Accordion>
</AccordionGroup>